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Documentation as an affective method of transferring 
information between individuals in order to reduce software 
maintenance costs is examined. Various categories of docu- 
mentation are identified and evaluated as to their effec- 
tiveness toward easing the maintenance effort. The concept 
of minimal documentation is introduced as the solution to 
the problem of determining the corract amounr of information 
required for a specific maintenance task. The idea of 
utilizing an explicit documentation hierarchy as rhe ideal 
method for storing explicit documentation is proposed. With 
the proper implementation of the documentation hierarchy, 
the minimal documentation concept can be realized, and the 
maintenance effort reduced. 
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I. IHTB0DSCTI3H 



A. THE FHOBLEH 

There is much discussion in the software engineering 
literature concerning the overwhelming cost of software 
maintenance. It has been indicated that in some systems up 
to eighty percent of the cost of a software system is 
consumed in the maintenance phase of the software life cycle 
[Ref. 1 ]. In order to properly maintain the software, it 
must be properly documented. Often the same person does not 
perform tasks in all phases of the life cycle, thus without 
documentation, continuity between the phases can be lost. 
Sometimes the only interface between each phase is a piece 
of documentation. This points out nhe criticality of docu- 
mentation in the software life cycle; if the documentation 
between phases is not done well, mu.ch of the work on the 
project must be recreated for subsequent phases. 

B. PURPOSE AHD APPROACH 

There is a lack cf cohesive discussion in current liter- 
ature concerning proper documentanion for efficient software 
maintenance. Because of the tremendous cost involved with 
software maintenance, an attempt to ease the maintenance 
effort needs to be made through the use of adequate 
documentation. 

The purpose of this thesis is to address documentation 
as a method of information transfer throughout the life 
cycle of a software project in the support of software main- 
tenance. Various types of documentation are discussed and 
evaluated as to their effectiveness toward easing the main- 
tenance effort. An attempt is mads to determine the proper 
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type and amount of information needed to effectively main- 
tain the software project. An effort is made to categorize 
and quantify different aspects of documentation based on 
task and user needs. The concept of a documentation hier- 
archy is put forth as a method for organizing these aspects. 
The idea is to give the receiver of that information 
precisely the amount of information required to complete the 
maintenance task. Too much information can bog one down 
with unnecessary details while too little information car- 
cause one to waste many hours in trying to understand the 
program. Thus a solution to the problem of accessing the 

exact quantity of documentation is offered. 

Chapter I gives an overview of the documentation problem 
as it relates to software maintenance. A description of the 
approach for the thesis is given along with some general 
definitions of terms used in the software maintenance envi- 
ronment. Also, the idea of minimal documentation is intro- 
duced in this chapter. 

Chapter II discusses software maintenance in detail 
with a look at the software life cycle. A software project 
scenario is described to set basic guidelines for the 
thesis. The different types of maintenance as they relate 
to the software modification task are described along with 
the identification of soma of the causes and solutions for 
the software maintenance problem. 

Chapter III introduces the idea of the transfer of 
knowledge between individuals as being the goal of effective 
documentation. This knowledge transfer is accomplished by 
utilizing various methods for recording information. 
Documentation is then categorized according to the type of 
information that is conveyed and also according to depen- 
dencies based on a person's skill and position on the main- 
tenance team. Finally, the role of documentation for a 
project is discussed. 
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chapter IV introduces the concept of a document at ior. 
hierarchy in support of minimal documentation. The levels 
of the hierarchy are based on the level of detail contained 
in the documentation. The various users of the documenta- 
tion need only to access the proper level in the documenta- 
tion hierarchy in order to have the minimal documentation 
that is required for the completion of the task at hand. 

Chapter 7 discusses the effectiveness of several 
specific forms of documentation in relation to the perform- 
ance of the maintenance task. The evaluation is made chat 
there is not a "besz” form of documentation for all mainte- 
nance tasks. The most effective documentation form varies 
with the maintenance task and the type of programming 
processing (sequential or concurrent) being used. 

Chapter VI consists of the thesis conclusions and 
recommendations. 

C. DEFINITIONS 

Certain basic definitions are needed in order to prop- 
erly address the issue of software documentation as it 
relates to software maintenance. For the purposes of this 
thesis, software maintenance will be considered to be -he 
process of updating and correcting a software system once 
the project is delivered and made operational. 

Software documentation is the recorded information that 
can be used to transfer information and ideas from one 
person to another. Unlike software maintenance, which has 
been defined to begin after the project is delivered, soft- 
ware documentation is produced throughour the entire soft- 
ware life cycle from the conceptual phase to the support 
phase. Since documentation follows the evolution of a soft- 
ware system, adequate and reliable documentation is inva- 
luable when it comes to maintaining the system. 



Minimal documentation is defined as the exact amount of 
documentation on a project that is required by the receiver 
to accomplish the receiver' s task. when the minimal docu- 
mentation concept is used, only the precise amount of docu- 
mentation that is needed is accessed, and the receiver is 
not forced to wade through unnecessary information. Just 
enough information is recorded so that the receiver is able 
to proceed with the job at hand. This, then, is an idea of 
documentation efficiency with no more and no less informa- 
tion being exposed to the receiver than is actually needed. 

Maintainability is a term that must be clarified. 
Martin and McClure (Ref. 2] define maintainability as the 
"ease with which a software system can be corrected when 
errors or deficiencies occur, and can be expanded or 
contracted to satisfy new requirements." Maintainability of 
a software system can be enhanced with the availability of 
adequate minimal documentation. 

Onderstandability is considered to be one of the most 
important concepts in the realm of maintainability. Martin 
and McClure define understa ndability as "the ease with which 
we can understand the program purpose and how the program 
achieves its purpose". Since documentation transfers infor- 
mation concerning software system evolution, the minimal 
documentation concept aids in the achievement of program 
understandabilit y. 



II. THE SOFT WARE lAINTEHAHCE PRQBIja 



A. THE SOFTWARE LIFE CYCLE 

The development of a software project goes through 
several phases from conception to acrual system operation. 
This development process is called the software life cycle. 
There are several models available to represent the soft- 
ware life cycle. The one used by the Department of Defense 
as indicated in Department of Defense Instruction 5000.1 is 
presented in Figure 2.1. It gives a reasonable representa- 
tion of most simple models. An advanrage of this model is 
that each major phase is broken into its subsequent 
subphases. This model is general enough to be applied to 
most software systems, with the details being left to the 
specific project. 

Documentation must be carried throughout the life cycle 
in order to promote understan debility in subsequent phases. 
Ultimately, the ideal documentation contains enough informa- 
tion such that when the program is completed and is opera- 
tional, it can be maintained effectively. 

The major problem with the Department of Defense model 
is the implication that is given concerning the flow of the 
software life cycle. One is left with the idea that as one 
phase abruptly halts, the next phase begins. In practice, 
the phase boundaries are somewhat obscure. Quite often work 
on one part of a phase begins before all work in a previous 
phase is completed. Also one gets the impression that there 
are no interdependencies between the phases. In reality, 
decisions made in one phase often directly affect the work 
of a subsequent phase. This makes each phase somewhat 
dependent upon decisions made in a previous phase. Also 
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Figure 2.1 Departaent of Defease Life Cycle aodel. 
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there are times when a decision made in one phase is 
determined to be unrealistic by restrictions or actions 
taken in a following phase. Therefore, a feedback mechanism 
is needed to carry information between phases in order to 
keep the software project development moving. 

Documentation is the method of recording information 
that is to be transferred forward and backward to aid in 
software modification. Figure 2.2 gives a more realistic 
view of the software cycles indicating some of the phase 
interrelationships [Ref. 3], 

Figure 2.2 shows validation and verification subphases 
in the requirements and design phases of the cycle. This is 
important because each phase should be verified as being 
possible and feasible as early in the cycle as possible in 
order to avoid unnecessary work. For example, it would be 
wasteful to work through to the implementatio-n phase only to 
find out that the project was never feasible in the first 
place. 

Studies indicate that the most economical time to catch 
and correct a problem is as early in the development cycle 
as possible. The cost of detecting and correcting an error 
more than doubles for each phase through which it passes 
undetected. This rate of cost increase holds true for each 
subsequent phase through which the problem passes without 
detection. [Ref. 3] and [Ref. 4], 

While the simplistic view presented in Figure 2.1 is 
relatively easy to comprehend, it is extremely important to 
remember the interrelationships between the various phases 
as indicated by Figure 2.2. with those interrelationships 
being kept in mind, the simplified life cycle model shown in 
Figure 2.1 will be adequate for use in this thesis. 
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Figure 2.2 The iaterfall Hodel of the Software Life-cycle. 
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B. TBE SOFTWiRE PROBIEH 



Bohem [Ref, 3] gives as some insights into the magni-ude 
of the economics involved with the software problem. The 
annual cost of software for the Onited States in 1980 was 
about 2 percent of the Gross National Product. The cosz is 
expected to grow faster than the general rate of the economy 
thus representing an even larger proportion of rhe Gross 
National Product as time goes on. The portion of the effort 
spent on software maintenance has increased faster than the 
effort spent on software development. With the growth of 
software maintenance tahing such a large portion of the 
total cost of a system, it would be wise to find ways to 
enhance the efficiency of the maintenance effort. 

Along with the economic issues of software maintenance, 
we must look at the social aspects of computers as they 
relate to software. Things such as computerized billing and 
banking have made a permanent impact upon the lives of most 
Americans. An increasing number of workers in the United 
States will be relying on computers to perform tasks 
involved with their daily work. By 1985 it is predicted 
that approximately uo percent of the working population will 
fall into that category. with this kind of computer and 
software proliferation, there will be continued growth in 
the amount cf software that is needed. This growth of soft- 
ware translates into a significant amount of necessary 
software maintenance as both the software system and the 
state of technology change. 

As the need for software maintenance increases, it 
becomes imperative that maintenance efficiency be improved. 
The idea of using minimal documentation in order to improve 
understandability, which in turn aids maintainability, is 
seen as a way to increase the efficiency of the software 
maintenance effort. 
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1 . Scenar io 

There are many types of programs that are developed 
ranging from very small to very large, and the size of a 
program can determine the software documentation issues 
related to that particular program. In order to address 
specific documentation issues we need to focus on a partic- 
ular Scenario. 

The program with which we will be concerned is one 
of medium length involving thirty to forty thousand lines of 
code. It is a software program that is to be maintained, so 
it is neccessary that software documentation be generated. 
(If a program were never to be modified, then documenta- 
tion would not be necessary.) For the purpose of this 
thesis, the program code is not considered to be a form of 
documentation. The program is one that was developed by a 
software development team (as opposed to being developed by 
a solo programmer) with documentation maintained throughout 
the development. The development followed the basic guide- 
lines as indicated in the Department of Defense life cycle 
model (Figure 2. 1) . The program developers are not the end 

users of the system. The program is embedded in an environ- 
ment that is subject to change. 

When a modification to the system is required, a 
change request protocol is followed in which a 

requested change is considered and a determination is made 
as to whether the change should be incorporated into 
the existing system. If the change is to be made, it is 
acted upon by a designated maintenance team. The personnel 
assigned to the maintenance team may or may not have other 
collateral duties in the organization, and they may or may 
not have had any connection with the original development of 
the system. Emergency changes are implemented as quickly as 
possible while routine modificatioa s are implemented in an 
annual system update. 
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The system is considered to have a life expectancy 
cf approximately twenty years, and it is further assumed 
that the system has been in operation for several years with 
maintenance being accomplished and documentation being 
updated accordingly. 

2 • Ond ers t a nd ab ility 

Underst andability is considered to be one of the 
most important concepts in the realm of maintainability. If 
a piece of software that is to be maintained proves to be 
both efficient and successful, yet is not understandable to 
the maintainers, it can be difficult and expensive (if not 
impossible) to modify to meet changing needs. 

In a good system, there is information available as 
to the purpose of the system, the proper use of the system, 
and the proper maintenance of the system [ Hef . 2]. All 
phases of the life cycle will have accompanying documenta- 
tion concerning the development at each stage of the system, 
and that documentation will carry the required informa- 
tion that aids in the under standability of the program. 

Familiarity is a factor that helps determine the 
effectiveness and understandability of a program. A person 
who is very familiar with the code and the functioning of 
the system would probably not have great difficulty in 
understanding the system, even if the documentation were 
somewhat lacking in quality and the system itself were very 
complex. On the other hand, the inexperienced or unfamiliar 
maintainer would probably have difficulty in understanding 
the program. 3e will see later how the factor of famil- 
iarity determines fcr an individual the level of detail 
needed in the documentation. 

Martin and McClure state that understandable 
programs generally have several common characteristics: 
structuredness; consistency; completeness; conciseness; and 
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documentation. Each of these characteristics will be 
discussed in more detail. 

a. Structuredness 

The effective structuring of a program increases 
understanding by standardizing the program format. The 
standardization will set restrictions and guidelines on the 
logical flow of the program. Program modules will be set up 
in a hierarchical manner with the order of execution deter- 
mined by the guidelines. The use of these guidelines for 
program construction will provide a consistent logic that 
will aid the underst andabil ity of the overall system. 

b. Consistency 

A program should be written in a consistent 
style in accordance with established programming standards. 
The structuredness mentioned above can be considered to be a 
method of developing a consistent style. It is difficult to 
understand a program in which the style of writing does not 
follow a common method of construction. This is sometimes 
difficult to accomplish when several members work together 
as a team on a project unless close communication conrrol is 
maintained. Consistent types of comments must be main- 
tained. When a module is described, it should handle the 
descriprion of the piece of code the same way every other 
module is handled in terms of the amount of detail discussed 
and the order in which the information is provided. 
Variable names should be selected with the same sort of 
reasoning throughout the program, and the program should be 
consistent with the design instructions. In-line comments 
should be used to clarify coding statements, and this prac- 
tice should be consistent throughout the program. There 
should be no visible evidence that the program was not 
written by one person with a consistent train of thought 
throughout the development process. 



19 



c. Completeness 



A complete program has all of its components 
available to use and to be perused by the maintainsr. The 
maintenance person must be able to access all parts of the 
program that are related to the maintenance function if 
understandability is to be accomplished. Any variables or 
modules should be included in a cross-reference scheme sc 
that the maintainsr can trace a program component throughout 
the system. Every unusual feature in the program should be 
clearly explained, and error massages should be made 
understandable. 

d. Conciseness 

A concise program is one that uses only the 
coding necessary to achieve the design requirements with no 
extra (perhaps unused) pieces of code. Every piece of code 
must be reachable by some action of the program. Onused 
variables and duplicate functions should be nonexistent and 
comments should not be excessively verbose or cryptic in 
meaning. Understandability decreases when complexity cver- 
talces simplicity. The system, though it in itself may be 
complex, can be simplified through the proper use of 
conciseness principles. 

e. Documentation 

Perhaps the concept that pulls all of the above 
understandability methods together is the development (and 
use) of good documentation techniques. The use of all of 
the above ideas that promote understandability in a system 
may not in themselves be successful. 

The structuredness of a program must be docu- 
mented in such a way that the structurization methods are 
understood by the maintainers. The consistent program must 
have the modules described and documented in a consistent 
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way. Com men z s should ba arranged near each module ro 
describe the module in some detail. The module comments 
should include the purpose of the module, the variables used 
or modified in the module, and a description of the output 
of the module. The module description should indicate the 
relative postion of the module with respect to other modules 
in the program to give some idea as to how the module was 

reached and how it fits into the program hierarchy. 

Documentation also aids understandabilit y by 
containing information as to the completeness of the 
program. Information is recorded as to how a module of the 

program is reached and how each module is related in the 

overall system scheme. Proper documentation should also be 
concise with only the necessary information being provided 
to the maintainer so as to enhance under srandability without 
confusion. 

. 3 . Mainte n a ne e Effort 

Since the maintenance effort represents such a large 
portion of rhe overall cost of a software system, a look at 
the software maintenance effort and ways in which to make 
this effort efficient by means of minimal documentation is 
in order. 

A survey of data processing maintenance activities 
by Lientz and Swansen [Ref. 5] shows that 'only half of 
the people who are assigned to maintain programs actually 
worked on their development. This fact is significant in 
that a lack of continuity of the original thinking occurs. 
To make matters worse, the number of development personnel 
assigned to the maintenance effort diminishes even further 
as the life of a software system is extended. Good docu- 
mentation passes information about the program between those 
personn-el developing the program and those maintaining the 
program, thus preserving the continuity of thought. 



21 



In order to gauge the magnitude of the mainrer.ance 
effort, Lientz and Swanson describe the effort as the result 
of rhe combination of four variables: system age; system 

size; relative amount of routine debugging; and the relative 
development experience of the maintenance personnel. As the 
system age extends, the system size tends to increase 
leading to a greater maintenance effort. with an increase 
in system size, the system tends to need mors routine debug- 
ging, again increasing the maintenance effort. When the 
system age increases, there is also an increasing amount of 
personnel turnover which leads to the declining relative 
development experience of the maintainers, thus again 
causing an increase in the maintenance effort. This mainte- 
nance effort increase, of course, results in a rise of 
overall maintenance costs. 

Minimal documentation can be used as a means to 
promote program understandability which will make the main- 
tenance effort become more efficient, and in turn cause a 
decrease in software maintenance costs. 

Typ es of Mai nten ance 

Generally software maintenance can be divided into 
three categories: corrective; adaptive; and perfective 

maintenance [Ref. 6]. Corrective maintenance is considered 
to be purely the correction of software errors. Though 
corrective maintenance is traditionally seen as the most 
obvious type of maintenance task, it is interesting to note 
that the time spent solely on the correction of errors 
amounts to only seventeen to twenty-five percent of the 
maintenance person’s time [Ref. 5] and [Ref. 7]. 

Adaptive maintenance is considered to be the process 
of adapring or changing the software to meet the environ- 
mental constraints of the system. An adaptive change would 
be considered to take place if a new operating system is to 
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be installed on the computer that is used by the program 
being maintained. This area of maintenance takes up about 
eighteen to twenty-five percent of the time spent on mainte- 
nance [Ref. 7], 

Perfective maintenance concerns the "perfecting" of 
the system by making user-requested changes to the software 
to make the system perform "better". It is interesting to 
note that while the perfective maintenance activity (some- 
times called providing enha ncementsj does not involve the 
act of correcting errors, it takes between fifty and sixty 
percent of the maintenance person's time — by far rhe largest 
single time chunk in the software maintenance effort 
[Ref. 7], This is in contrast to what is generally consid- 
ered to be "real" maintenance, that of the corrective type. 



5 . Cau ses o f Ma inten ance Pro blems 

It is beneficial to look at some of the things 
that create the need fcr software maintenance and ways that 
the use of proper documentation can ease the maintenance 
task . 

Schneidewind [Ref. 8] indicates that several items 
bring about maintenance problems. One is the facr that 
maintenance is often viewed by both designers and users as a 
task that is not very glamorous. This leads to a tendency 
for personnel to want only to design systems while letting 
the maintenance aspect of the system take a low priority. 
This leads to many of the maintenance problems being ignored 
during the development phase, including the proper documen- 
tation of the project as it progresses. Maintenance is 

often not even considered during the software development 
process. 

In reality, documentation and maintenance ideas must 
parallel system development through all of the software life 
cycle phases, and actually become an integral part of the 
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design criteria. This is necessary if a program is to be 
easily understood and efficiently operated and maintained. 

Glass and Nciseux [Ref. 9] show that a traditional 
approach to the software problem has lad to the practice of 
simply tacking on maintenance aids as an afterthought. The 
concept of software maintenance, particularly in something 
other than that of a corrective nature, seems to be some- 
thing that receives very little attention. 

Now let’s lock at the software maintenance problem 
as viewed by managers who plan the maintenance effort based 
on how they perceive the maintenance problem. Lientz and 
Swanson [Ref. 5] report in a study that managers perceive 
the lack of user knowledge as by far the most dominant 
problem in the maintenance effort. Following the user 
knowledge problem in order of highest to lowest significance 
were: programmer effectiveness; product quality; programmer 

availabilt iy; machine requirements; and finally system reli- 
ability. When the system is properly documented, user 
knowledge about the program development and' maintenance 
techniques can be increased. Increased knowledge can cause 
more efficient use of the maintainer's time thus making the 
maintainer available more often to perform other tasks. 
Documentation can also be used to record machine require- 
ments in such a way that they are mads available for consid- 
eration in maintenance decisions. When documentation is 
used properly, it can reduce these problem areas as 
mentioned and result in an overall increase in system 
reliability . 

The study further revealed a misconception commonly 
held by managers. Problems were perceived by managers to be 
greater if a lot of corrective maintenance time was spent on 
the system. As mentioned earlier, corrective maintenance is 
not the big time consumer whereas perfective maintenance 
does in fact consume the bulk of the maintainer's time. It 
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is interesting to note that there were no significant find- 
ings to indicate that there was any time at all allotted to 
the maintenance personnel for the act of performing purely 
perfective maintenance. When it is understood that most of 
the actual maintenance time is spent in making program 
enhancements (that is, the perfective maintenance), it 
becomes clear that managers need to re-evaluate the way they 
allot time for maintenance. 

Another reason for maintsnaace problems can be 
considered to be both a cause and a resulr of the above 
mentioned problems. This reason for maintenance problems is 
the lack of good documentation. Schneidewind points out 
that one of the problems involved with software maintenance 
is that no tracebility is built into the software. This 
problem could be resolved with the appropriate documentation 
technique. la order to convey ideas from old maintainers to 
new maintainers, good documentaion is needed. For example, 
formal specifications of the problem for which the system is 
designed must be presented and documented sc that a later 
change to the program can be evaluated against the docu- 
mented reason for a parricular design system. This thesis 
will explore the documentation problem in more detail in 
later chapters. 

6 . Soluti ons 

As implied from the above discussion of the causes 
of the software maintenance problem, the use of proper docu- 
mentation is the key to many maintenance problem solutions. 

The solutions require the cooperation of managers, 
users, and maintainers. Good maintenance techniques are 
also necessary and must begin at the design and require- 
ments phases of the life cycle. Several ideas are presented 
by Schneidewind to ensure good maintenance practices and 
good documentation. 
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To Start, good maiatenaace techniques must be 
planned from -he beginning of a software project. This 
means that the project must be designed with maintenance 
integral to the entire life cycle, non added later when nhe 
project is completed. Since enhancements take up mosn of 

the maintenance effort, it is aeoessary that the design 
ideas incorporate the understanding that enhancements will 
take place and that managers plan maintenance time 
accordingly. 

One way to enhance maintenance personnel under- 
standing is to use modularity techniques in the design of 
the software project. This means that common ideas or 
concepts should be kept together in a logical sense that 
would be easy for the maintainer to follow utilizing proper 
documentation. The documentation should be able to convey 
the module concepts used in the design of the software to 
the person who needs to make software modifications. 

Along with the modularity techniques, the idea of 
independence among code, data, and dana base is in order. 
This independence allows certain amounts of code, functions, 
subroutines, etc. to be changed without devastating effects 
taking place in other portions of the program. Information 
hiding techniques are valuable when designing a program 
with modular independence for ease of maintenance. 

Schneidewind also gives several ideas concerning the 
proper development of documentation along with the project 
in order to ensure the ease of maintenance. One idea is to 
design the documentation first. Many a programmer knows how 
bothersome this task can be. Just think of how many times 
the flow charts or refinement procedures were written after 
the program itself was actually written. The problem with 
writing the documentation after the program is completed is 
that the documentation that is supposed to aid in the devel- 
opment and decision making processes cannot possibly be 
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used. Also the docuaient ation becomes static in naxure. 

That is, ail the dynamic creativity cannot be included in 
the process of documentation and all we see is the final 
resulting document. This is very much like a college 
professor receiving a math or physics exam with only the 
answers and no actual work shown. 

Another idea for good documentation is that the 
specifications and standards should require aids that 
promote the understandability of the program. This 
includes the concept of providing comments in the program 
listing, references in the source listings for certain soft- 
ware specifications, and any other references necessary to 
trace through other related documents. 

System specifications should be designated as to the 
kind of information that is to be conveyed to the maintainer 
via documentation. This idea implies that certain types of 
documentation convey certain kinds of information, and that 
only certain bits of information are required for certain 
maintenance functions. The idea of different kinds of docu- 
mentation delivering various kinds of information, and the 
effectiveness of the forms of documentation will be 
discussed below. 
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III. SOFTWA RE DOCaaSH TATIO N 



This chapter covers many aspects of software documenta- 
tion. Some background is given on documentation in general, 
including a discussion about the purpose of documentation. 
The various categories of documentation are explained based 
on the characteristics of the documentation and the needs of 
the user. Control and development documentation is 

discussed, as is static and dynamic documentation. Also the 
categories of implicit and explicit documentation as they 
pertain tc the maintenance role are explained. 
Documentation dependencies with regard to skill levels and 
position level of personnel on the documentation team are 
discussed. 

A. DOCDMEHTATION BACKGSOOHD 

The primary purpose of documentation is to impart knowl- 
edge about the system to pertinent personnel by trans- 
ferring recorded information. Other than the code itself, 
nhe only source of written information about the program is 
the documentation. Misunderstandings can occur when our 
informal, abstract ideas are translated into formal, 
concrete pieces of information. This information transfer 
is accomplished by recording on various forms of infor- 
mation storing media. This includes such methods as manu- 
ally recording facts on paper, or electronically placing 
them in a computer memory. These various information 
recordings become forms of documentation. The documentation 
challenge, then, is to find a way to ensure the unmolesxed 
receipt of intended concepts by the documentation users. 
When this challenge is met effectively, documentation is 
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ccnsidersd to have accomplished its goal of successfully 
conveying relevant, information from one person to another. 
Chapter V discusses in more detail the particular documenta- 
tion formats and their relative effectiveness. 

One cannot hope to effectively transfer knowledge about 
the system by simply flooding the maintainer with all the 
information that can possibly be assembled. It is necessary 
to distinguish between types of documentation, and discern 
the type of information that each conveys. Not all types of 
documentation are adequate for all types of information 
transfer, and consequently, not good for all types of main- 
tenance chores. 

B. DOCDBEHTATION CATEGORIES 

While the idea of rransferring information is clear, the 
idea of what kind and how much information to transfer is 
not so clear. The amount of information to transfer is both 
task dependent and programmer dependant. Both the mainte- 
nance task to be accomplished and the level of expertise of 
the maintenance person should be considered when deciding 
upon the caregory of documentation to be used. For example, 
if the documentation is to be used by someone who is vary 
familiar with the system and the type of changes to be 
applied to the program, the documentation needed would be 
of a level that is far less detailed than that of someone 
who had never worked on the system before. It would be 
helpful to find ways to categorize documentation in order to 
gain an understanding of rhe values of each. 

1 . Int ern al and Exter nal Docume n tation 

One way of categorizing documentation is based on 
how the documentation itself is transported (internally or 
externally) . Internal documentation is the documentation 
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that is carried along with the code (perhaps in a separate 
file. It is usually embedded in the form of comments or 
cross reference listings, and is not executable. It is an 
integral part of the program, so it is always available. It 
is easy to maintain because it is as easy to update as the 
code itself. When a software modification is made, it is a 
simple matter to modify the internal documentation. Because 
of the ease of update, internal documentation is considered 
by programmers to be very reliable, and the programmers 
have a high level of confidence in the currency and accuracy 
of the internal documentation. 

External documentation is the documentation that 
exists outside the source code of the program. This 

includes such things as data flow diagrams, flow charts, and 

any other mode of recording program information that is 
not an integral part of the program. This type of documen- 

tation is more difficult zo maintain than the internal docu- 
mentation because it usually exists in hard copy only, thus 
pen and ink changes are required for making documentation 
modifications. Because of the difficulty encountered in the 
updating of external documentation, often it is not updated 

when the system is modified. This leads to a low level of 

trust among programmers with regard to the reliablility of 
external documentation. This low level of confidence in the 
currency of external documentation is often perpetuated by 
the feeling that there is no reason to update it since it is 
not current anyway, and even if it is updated, it won't be 
trusted. 

2. Dynami c and Static Documenta t ion 

Documentation can also be considered to be either 
static or dynamic in nature. Dynamic documentation involves 
the conveyance of ideas about the actual developmental 
thought processes. This would include the recording of 

ideas that begin with the first thoughts in the conceptual 
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phase of the life cycle. It also iacludes the aisr.akss aade 
and the ideas considered and rejected for any reason. Prior 
mistakes and the reasons as to why they were misrakes can 
provide vital insights to the maintainers when new changes 
are being considered. 

The dynamic nature of the documentation cones from 
the fact that the entire decision-making process can be 
actively recorded and transmitted to the receiver of the 
documentation. The significance of this type of documenta- 
tion, then, is the fact that later enhancements to the 
program (remember, it is the enhancements that make up the 
biggest part of the maintenance workload) can be considered 
in light of original design decisions. Much redundancy in 
the consideration of enhancements stands to be saved when 
proper dynamic documentation is used. 

Static documenration can be considered to be the 
"final product" of the documentation process. It is a 
recording of the current static state of the program at some 
point in time, and it does not provide any indication of the 
dynamics involved in the evolution of the program reaching 
that state. This type of documentation includes things 
such as a system or program flow chart or a resource 
diagram. It is this type of documentation that conveys the 
ideas of the program or system itself, and how it functions. 

It must be realized that both of these types of 
documentation are necessary for the proper transfer of 
knowledge from the designer to the maintenance person. 
Without both types, either the original thought "flavor" of 
the designer's intent is lost with the passage of time, or 
the understanding of the processing of the program is 
lost. 
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3 . Implic it and Expli c it Doc umaa tatio n 

Another categorization of documentation is the 
notion of implicit and explicit documentation. Explicit 
documentation can be thought of as the documentation than is 
physically available, in whatever form (dynamic cr static), 
at varying levels of detail. Explicit documentation cculd, 
therefore, include documentation such as comments, manuals, 
and flow diagrams. 

Implicit documentation is a more subtle and abstract 
type of documentation. This type of documentation consists 
of the "essence” of a program that is made available by 
consolidating information from one or more forms of einher 
the dynamic or static documentation. This concept of 
implicit documentation, then, involves a synergistic effect 
that provides a high level understanding of the system 
without large amounts of explicit physical information 
necessarily being accessed. Implicit documentation provides 
the "Big Picture" for the receiver of the information when 
various amounts of physical documentation are assimilated. 
Thus implicit documentation captures the concept of trans- 
ferring between individuals knowledge that would be diffi- 
cult to impart through language or explicit documentation. 

It is sometimes very difficulr to convey abstract 
ideas through the use of explicit informational documenta- 
tion, yet enough documentation (but not so much as to over- 
whelm) must be explicitly available to successfully generate 
the implicit documentation notion. This supports the 
concept of minimal documentation. 

C. DOCOHEHTATION DEPENDENCIES 

Yet another way to categorize documentation is to 
consider audience-dependent and life cycle phase-dependent 
documentation divisions. It is necessary to understand the 
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nesds cf rhs audience for which the documentation is 
intended and also the life-cycle phase no which nhe documen- 
tation is related. These determinations are necessary so 
that the documentation user who is knowledgeable abour the 
system is not completely bogged down by the effort of 

trying tc sort through a myriad of details that have nothing 
to do with that particular maintenance task, or are super- 
fluous in the sense that the user already knows the neces- 
sary details. By the same token, it is inefficient for a 
person who is not well versed in cerrain aspecrs of the 
project to spend many hours searching through lots cf docu- 
mentation just to find out something specific about the 
program on which maintenance is to be conducted. There 
must indeed be a balance between very detailed and high 
level documentation. The idea is than unnecessary work that 
adds to the overhead of the maintenance task should not be 
given to the maintenance person. (More is discussed in 

Chapter 7 about how to access the proper level of detail of 
docu mentation. ) 

Hheii considering audience-dependent documentation, 
several factors must be taken into account. These 

factors include the reader’s skill level (or familiarity 
with the project), the reader’s position relative to the 
maintenance job, and the particular type of maintenance to 
be accomplished. A skilled person can be defined as one who 
understands basic organization programming policies or tech- 
niques. The skilled person often possesses the quality of 
familiarity discussed earlier. 

Different kinds of documentation are appropriate for the 
different factors mentioned above, and in order to run the 
maintenance job effectively, these kinds of documentation 
are critical. 
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• Skill Level 

In considering the idea of skill level for the docu- 
mentation user, the level of documentation detail should be 
of concern. The documentation should be of sufficient level 
so as to give the user the precise amounr of detail neces- 
sary to carry out the required maintenance function. This 
means that, if the user is skilled, the provided document 
should not contain minutely detailed explanations of rhe 
program if the ideas are commonly understood. On rhe other 
hand, the documentation must be an adequate level of detail 
so as to provide the unskilled person with the needed amounr 
of system specifics. 

The ideas of explicit and implicit documentation 
come inro play here. For the highly skilled user, the 
amount of physically explicit documentation can be small and 
condensed in nature. The amount of implicit information 
would be large because the skilled user can accept high 
level concepts that do not have to be explicitly described. 
That is, a highly skilled user can make use of implied 
notions, such as the notion that the data in a certain 
program goes through a ’’sort and eliminate" routine. Hera 
the explicit documentation would consist of the information 
that the data is sent to the routine, while the implicit 
information would be made up of commonly understood details 
of the routine itself. 

as for the unskilled user of the documentation, the 
nature of the explicit and the implicit idea conveyance 
would be quite different. The unskilled user would need 

much more explicit information to absorb the same amount of 
knowledge of the portion of the program to be maintained. 
The necessary explicit information would likely include many 
of the specific details of the "sort" and "eliminate" 
routines separately. If the criteria for elimination of 
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certair. data were understood by the unskilled user at -his 
level of detail, then those details would be considered to 
be implicit inf orma ticn. If those criteria were unknown to 

the unskilled user, then the explicit documentation concept 
must move down another level of detail to incorporate these 
details explicitly. The levels of detail are translated 
continually from the implicit to the explicit realm as the 
need for information detail (determined by the skill level) 
moves down to lower levels. 

Conversely, as the skill level of the user 

increases, information and details required by the user move 

from the explicit to the implicit realm, thus allowing 
broader concepts to be absorbed by the user. As more 

implicit information is required by the user, a corre- 

sponding lesser amount of explicit information (or documen- 
tation) is required. 

The consequences of having less explicit information 
being required means that less documentation (and conse- 
quently less overhead) needs to be sorted through in order 
to complete the maintenance task. The end result is that as 
skill level increases, less time is required for the 
specific maintenance rask, and a corresponding maintenance 
efficiency results. 

2 . Positi on 

A look at the idea of a person's position with 
regard to the maintenance effort is useful. In order to 
better understand how the relative position of the person 
utilizing nhe documentation affects documentation needs, 
first we must know whether the person is considered to be a 
maintainer, a manager, or a user. 
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a. Maintainer 

The maintainei: is defiasd to be the parser, who 
is actively involved in rhe actual act of maiarainirg the 
program. The maintainer requires the lowest level of 

abstraction of documentation, or the most detailed level of 
information because of the actual physical maintenance that 
is accomplished. The type of documentation required by the 
maintainer to successfully complete the maintenance task 
then will be on a level that is fairly detailed. The depth 
of detail required will of course be dependent upon the 
maintainer’ s skill level or familiarity as discussed 
earlier. The documentation type will be of the kind that 
will promote the detail necessary to complete the job. The 
amount of explicit documentation will also be determined by 
skill level and familiarity. 

As far as dynamic documentation is concerned, 
the maintainer relies less heavily on this level of documen- 
tation than on the static documentation. The maintainer is 
very concerned about the present state of the program 
because the present state is what is to be modified. The 
decision as to whether or not to make the modification is 
usually made at a higher level, and thus the dynamic docu- 
mentation will be better used at that higher level (probably 
the manager level) . 

b. Manager 

The manager category can be defined so as to 
include anyone who is directly connected with the mainte- 
nance of the system, but not actively involved with the 
actual physical maintenance of the project. This could 
include the maintenance team leader in rhe supervisory role, 
the department head, or higher level decision makers. The 
type of documentation that the manager needs should be of a 
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much higher level of abstraction requiring less derail rhan 
that required by the maintainer. This means that much more 
documenr ation of an implicit nature is acceptable in order 
to meet the needs of the manager level personnel. The 
greater the amounr of implicit documentation needed, the 
less the amount of explicit documentation necessary. 
Likewise, the less the detail level of the explicit documen- 
tation, the less the amount of details through which the 
manager must sort. The smaller amount of detail required 
leads to the saving of time and money. 

The manager could very well be the biggest user 
of dynamic documentation. The manager at the maintenance 
group supervisor level is likely to be the one who must look 
at the way prior decisions were made in order tc verify the 
practicality of requested maintenance enhancements. The 
manager might want to avoid re-deciding something that is 
already a given and has been recorded in the dynamic 
dccu mentation. 

The manager could also be a very heavy user of 
static documentation in the sense that it might be necessary 
to reference the present status of the maintenance effort in 
order to properly set up the maintenance team. Thus the 
manager must rely heavily on the static documentation to 
understand the program status after design and also to 
modify the existing documentation as the program is modi- 
fied. This also implies that dynamic documentation by the 
maintenance team is occurring along with program modifica- 
tions, and the manager is responsible for updating or 
creating the appropriate dynamic documentation. 

c. Oser 

The user is anyone who actually uses the system 
(the pilot using an avionics system, a fire control techni- 
cian on board ship, etc.) The user might be someone who is 
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considering purchasing services or produces from the company 
and is interested in the seability of the company as a 
whole. The system is a viral part of the company, and 
consequently the user might be interested in the program or 
system from a very abstract point of view. Orher than 
specific user’s manuals and system operational guides, the 
user needs little or no detailed information and can 
tolerate a large amount of implicit documentation. The 
amount of explicit documentation required for the user will 
be very small indeed, perhaps even a simple listing of the 
systems cr programs available to the company. The user 
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dynamic documentation and has very little interest in 
static documentation. He does not really care about the 
design decisions that occurred during the development of the 
system, but merely about the fact that there exists a 
system sufficient for his needs. 

D. ROLE OF DOCOMENTiTION 

The idea of implicit and explicit information can be 
utilized here. Returning f or a moment to the example in the 
last chapter concerning the likening of the receipt of one 
final piece of documentation to that of a college professor 
receiving only the answers on a physics or math test without 
explanation as to how the answers came about, more 
discussion is in order. The dynamic nature of showing the 
work, whether the work was on an exam or on a program, helps 
both the programmer and the maintenance person (cr the 
student and the professor) follow the design and development 
of ideas. Since documentation, as described earlier. 



38 



involvas the transfer of ideas, it is crucial that these 
ideas be transferred dynamically in the form of progressive 
documentation. It is difficult to understand the thought and 
development process that goes into a problem when all that 
is seen by the receiver of the information is the final 
solution. 

We need not worry that the final documentation product 
might contain some recording of our initial erroneous 
efforts. In fact it might be helpful to the maintainer if 
the initial trial and error efforts were made available. 
It could save the maintenance person the redundant effort of 
trying tc rethink the designer's ideas in order to possibly 
change a previous logical decision. 

The complete documentation could also keep the main- 
tainer from overlooking some critical piece of information 
that would make the newly proposed enhancement an obviously 
bad mo^ve. Another advantage of documenting the creative 
process is that ideas that were not feasible (technologic- 
ally or environmentally) at the time of design, and conse- 
quently rejected, could be used during the maintenance phase 
as a result of system requirement ohanges or technological 
advances. 

Ideally, then, the maintainer will not receive as docu- 
mentation something as simple as the statement that a 
sysrem will use red ribbons for printed output. This gives 
no indication as to how much thought, if any, went into the 
decision. When the suggestion for an enhancement to allow a 
different color for printed output, the maintenance person 
must try to second guess the' designer's decision as zo why 
red was selected, and if another color is possible. If this 
knowledge were made readily available, the maintainer could 
possibly head off an expensive analysis of colored printed 
outputs that would discover that the designer already knew 
that rad printouts were the only ones rhat could be read 
under the special lighting needed for a security project. 
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IV. DO CDME N TAT ION aiERARCHY 



The idea of a documentation hierarchy is introduced 
along with an explanation of the proper use of the hierarch- 
ical organization and how it promotes the concept of 
minimal documentation. System and program documentation are 
discussed in detail as they relate to both the system hier- 
archy and the maintenance task. 

A. SYSTEM DOC 0 MENTATION HIERARCHY 

One problem rhat faces the manager is how to wade 
through all available documentation in order to glean out 
the pertinent information for the present task without 
getting togged down with a massive volume of material. The 
same problem is faced by the maintainer who may not need to 
know all the system design information when the task at hand 
(as determined already by the managerial decision-making 
process) is simply to modify a small section of code. It is 
clearly wasteful in this case to force the maintainer to 
sort through huge amounts of irrelevant material concerning 
high level system information just to locate information 
pertaining to the immediate code modification task. 

The user requires information about the system on a high 
conceptual level, but the deluge of unorganized documenta- 
tion with all levels of detail would require time consuming 
searching, and most of the detailed information would be 
utterly useless. 

A solution to the problem of unorganized levels of 
detail in documentation is to construct an organized hier- 
archical structure for the various forms of documentation 
based on the level of detail. This documentation hierarchy 
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can provide precisely the appropriate level of derail in the 
available dccuinentati.cn for the receiver, regardless of 
whether the receiver is the user, manager, or maintainer. 
Figure 4.1 provides an example of a system dccumentat ion 
hierarchy organization that indicates the various levels of 
detail involved in the documentation of a system. 

All of the documentation is available to the proper 
receiver in a concise format that gives the receiver the 
least amount of detail necessary (thus promoting the concept 
of minimal documentation as mentioned earlier). As more 
detail is needed, more explicit documentation is accessible. 
This promotes undarstandabi lit y and contributes to an effi- 
cient maintenance effort. 

The system documentation hierarchy of Figure 4.i shows 
arrows that indicate a downward and upward flow of documen- 
tation access. As progress is made down to lower levels on 
Figure 4.1, more detail is attained in the documentation. 
Conversely, as movement is made up the levels, less detailed 
descriptions and larger concepts are accessed. 

3 . SYSTEM DOCUMENTATION 

To understand more about the system documentation hier- 
archy, it must be understood what is meant by system docu- 
mentation. A system can be defined as one or more programs 
that work in conjunction to perform a particular function. 
The system can be very simplistic, such as a simple vote 
counting sysrem, or it can be very complicated as in the 
case of a sophisticated weapons system. Since a system has 
been defined as the combination of cne or more programs that 
perform a function, system documentation is defined as the 
documentation of the overall system life cycle from 
project conception phase through the support phase. 
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Figurs 4.1 System Docameatation Hierarchy. 
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Systam documentation contains racorded information 
perraining to the completa description of the evolution of a 
system throughout its life cycle. It includes a record of 
the development process and the maintenance history in 
either implicit or explicit form. System documentanion 
contains both dynamic and static information and can be 
used by maintainer, manager, and user personnel. The 
specific form of documentation is dependent upon the 
requirements of the task to be accomplished and the needs of 
the receiver. 

Since a system is made up of one or more programs, 
program documentation is considered to be included as a part 
of the system documentation. In Figure U. 1 program documen- 
tation consists of levels 3 and 4. Both sysrem and program 
documentation are discussed in greater detail later in this 
chapter. 

1. Level 1 



The overall system documentarion follows a hierarch- 
ical structure with varying levels of detail as shown in 
Figure 4.1. The highest level of abstraction for the 

system, level 1, includes a narrative description of the 
sysrem itself and a description of the system environment 
along with any assumptions about the system. The environ- 
mental description would include information pertaining to 
the system hardware and software environments. This 

includes system restrictions and limitations that might 

result from certain hardware or software constraints under 
which the system must operate. Military applications such 
as an avionics system or a submarine weapons system would 
dictate specific environmental restrictions because of the 
very nature of the system activities. 

It is in this level that the documentation 
contains the most abstract information about the project. 



This level of detail would probably be most often used by 
the user personnel, but this non*detailed narrative level 
could also be of use to the manager and maintenance 
personnel who require an overall understanding of the 
system. 

2 . level 2 

Level 2 is the next level of abstraction in the 
hierarchical structure and contains slightly more derail 
than level 1. This level includes any system flow informa- 
tion, such as perhaps system flow diagrams, and system input 
and output descripticns. The inter-program module descrip- 
tions are included in this level; this level gives informa- 
tion about how individual programs are inter-related in the 
sysrem. This type of information can be conveyed with the 
use of narrative remarks. 

Since level 2 system documentation includes informa- 
tion such as system input and output specifications and 
requirements, maintainers and managers find this input/ 
output information to be valuable because they must ensure 
that the maintenance of the program is accomplished in such 
a way that the output requirements are correctly attained 
when the appropriate system inputs are given. 

Managers need to know the system input and output 
specifications that fit user needs in order to ensure main- 
tainers have the proper information as translated from the 
user (who very likely is not as technically oriented as the 
manager or the maintainer) requirements. Thus the managers 
can take the user input and output requirements as requested 
by the users and translate them into an understanding 
between the maintainers and the users in order that effec- 
tive maintenance can be accomplished. 

Users obviously play an important role in the gener- 
ation of the general input and output specifications, and 
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these specifications must make sense to the managers before 
the maintainers can be expected to understand and perform 
maintenance tasks. An understanding between users and 
managers must therefore be reached as zo what the users want 
(or think they want) . The prudent user will heed management 
advice when considering reasonable input and output formats. 

System logic information is also a part of level 2 
of the system documentation hierarchy, and it conveys the 
logical flow of the project. This logical informaricn could 
include a narrative section that describes the purpose of 
the system and how it is logically constructed. The hier- 
archy of programs, functions, and modules can be described 
in the narrative. The system flow documentation concerning 
the relationship of the individual modules can take the 
form of system flow charts or flow diagrams with accompa- 
nying comments. 

The inter- program module descriptions provide infor- 
mation about the relationship of the programs to the sysrem 
and 'to each other. Any restrictive characteristics or 
program environmental considerations are included in the 
inter-module narrative. 

The rest of the lower levels of abstraction make up 
the program documentation portion of the documentation hier- 
archy. It is in these levels rhat the degree of detail is 
such that the system is no longer the focal point of the 
documentation, and the program specifics are brought into 
view . 

C. PBOGRAS DOCOMENTATION 

Program documentation, as indicated above, consists of 
the recorded information about the program itself. It is of 
a more detailed nature than the system documentation and is 
most useful for the manager and maintainer. It contains 
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information pertaining to program module construction and 
logic flow. Data structure, data flow, and control flow 
specifics are recorded so that the documentation receiver 
has relevant program information available. Programming 
methodology techniques and maintenance history become part 
of the program documentation as well. Dynamic documentation 
describing inter-module concepts and structures is included, 
but static documentation makes up the bulk of the program 
documentation. Specific explicit forms of program documen- 
tation include flow charts, English narrative statements, 
resource diagrams, and Petri nets. 

While all of the levels in Figure 4.1 represent system 
documentation, levels 3 and 4 can be combined to make up the 
program documentation portion of the system documentation 
hierarchy. 

1 . Level 3 

Level 3 of Figure 4. 1 is the first level of the 
program documentation and conveys a particular program 
description. Particular program constraints that deal with 
specific programs are described in Level 3 along with any 
high level narrative about the program itself. Level 3 does 
not contain any inter-program relationships with other 
programs. It is the level that deals wirh strictly a single 
program. 

This level of abstraction is more detailed than 
levels 1 and 2, and is very useful to both the manager and 
the maintainer. The manager needs to keep the high level 
program concept so that the maintainers can be properly 
managed without forcing the maintainers to be concerned with 
any unneccessary abstract information. The manager must 
keep the pregram concept in mind and relate it no the rest 
of the system (level 2 and higher) . 
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The maintainer can, however, use this level of 
detail to aid in rhe understanding of how a particular aain- 
tanancs task is constrained. The aanager is responsible for 
the overseeing of the inter-program module relationships, 
but a knowledgeable mainranance person can be of 
immeasurable aid to the wise manager in this area. 

2 . Le v el 4 

The next lower level of abstraction, level 4, 
provides the greatest level of derail. This level is used 
very heavily by mainrenance personnel, and often by manage- 
rial personnel. This level consists of very detailed 
descriptions such as program flow information and input/ 
output formats. Much of this documentation is very explicit 
in nature. It can be static or dynamic. Flowcharts, 
inter-cods comments, logic, and data flow diagrams are 
included in this level of documentation. It is this level 
of detail that describes program modules in enough detail so 
as to promote under standabi lity among maintainers. 

While maintainers are the heaviest users of program 
documentation, and users are the primary users of the higher 
level system documentation, managers must bridge the gap 
between the two levels of documentation. Managers are 
involved with high level decisions that require an overall 
system understanding, yet they must also be involved with 
some of the lower levels of program documentation in order 
to properly manage the maintenance functions. 

D. DOCOHEHTATIOH BIEBABCHI OTILIZAIIOH 

The documentation hierarchy is set up so that anyone can 
access the hierarchy at any of the indicated levels, and 
thus be exposed to the level of detail characteristic of 
that particular level. If more detail is needed for a given 
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task, then a simple move down to the next level for greater 
detail is permitted. By the same token if it is determined 
that the level accessed is too detailed for the particular 
needs of the person using the documsntation, then the arrow 
is simply followed up to a higher level of abstraction that 
meets the desired needs. 

Each form of documentation, then, is catalogued as to 
its detail level, and a menu format (either paper or elec- 
tronic) can be utilized to directly access the level needed. 

with the capability of moving either direction in the 
hierarchy structure, great flexability is built into the 
system, and only the exact amount of documentation needed is 
accessed. This promotes the minimal documentation concept 
and, therefore, keeps the documentation overhead down to a 
minimum. The amount of useless information that must be 
waded through in order to find the proper documentation is 
kept low as a result of proper utilization of the documenta- 
tion hierarchy concept. 
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V, B7ALDAT I0N OF FORMS OF D OCD ME NTA TIOH 



Chapter III discusses the varioas rypes of documentation 
and how they relate to the maintenance effort. It is impor- 
tant to carry the documentation discussion further and talk 
about not only the types of documentation that are useful, 
but also some specifics as far as physical arrangements are 
concerned. The discussion will focus on explicit types of 
program documentation, and how some of the physical charac- 
teristics of the documentation affect the efficiency of 
maintenance performance. 

A. EVALDATIOH EXPERIMENTS 

When dealing specifically with programming documentation 
(levels 3 and 4 of Figure 4.1) which is most nften used by 
maintainers, it would be helpful to understand which 
different forms of documentation are most effective. 
Chapter III discusses the different types of information 
utilized by users, managers, and maintainers, depending on 
the maintenance task and the documentation receiver. This 
chapter discusses some specific forms of documentation and 
how effective they can be in promoting understandability for 
efficient program maintenance. 

It has been determined by General Electric studies 
[Ref. 10] that the best form of documentation to be used for 
maintenance is heavily dependent on the type of program 
processing that takes place, in particular whether it is 
sequential or concurrent processing. 
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1 . Doc ume n tat ion for S equent ial Pro cessing 

In determining the most effective type of documenta- 
tion format for sequential processing, a primary concern 
must involve the type of symbology used to present the 
information. It would be beneficial to ascertain the best 
form of symbology as seen by the maintenance personnel in 
terms of maintenance efficiency. 

The three symbology types used in the General 
Electric Studies consist of narrative Englist text, an 

abbreviated program-like language called Program Design 
Language (PDL) , and ideograms. The narrative text is 
frequently embedded in the source code as either global or 
in-line comments. The PDL is succinct and uses strictly 
defined keywords to describe arguments or predicates. 
Ideograms are often found in flow charts and HIPO charts. 



Sets 


of ideograms represent 


processes 


in 


a program 


[Ref. 


11 ]. 










Another primary concern 


which must 


be 


dealt with 


when 


weighing effective documentation is 


the 


issue of 



spatial arrangement. Spatial arrangements can aid main- 
tainers in understanding the flow of control in a sequential 
program, and it would be helpful if the best spatial format 
could be determined. The spatial arrangements provide 
different ways of representing control flow and nesting 
levels. The spatial arrangements used in the experiments 
are sequential, branching, and hierarchical representations. 

The sequential arrangement represents both the 
control flow and the levels of nesxing in a vertical manner. 
The branching arrangement presents the flow of control in a 
vertical manner while the nesting levels are presented hori- 
rontally. Finally, in the hierarchical arrangement, the 
control flow is represented horizontally and the nesting 
levels are presented vertically. 
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The sequential processing exparimenrs were designed 
to run the gamut of many of the maintenance tasks performed 
by programmers. The tasks included answering questions 
about pregram coding, program debugging, program modifica- 
tion, and program operation. The maintenance tasks were to 
be completed using the various forms of documentation being 
tested. The studies were conducted with professional 
programmers who were asked to answer questions about 

programs. The programmers were allowed to reference only 
the various forms of documentation having the spatial and 
symbology characteristics mentioned above to get information 
about the programs. 

Nine specif ication formats wars presented to the 
programmers for their use in the experiments. Each of the 
three types of symbology was presented in each of the three 
spatial arrangements. 

The participants were also asked to choose which 
format of documentation they found to be the easiest to use. 
This choice was then weighed against the type of documenta- 
tion that produced the best results in terms of maintenance 
effectiveness. 

In the first experiment, the programmers were asked 
to answer backward and forward-tracing questions and input/ 
output questions about the program using the test documenta- 
tion provided. 

The results showed that the sequential PDL,' the 
branching PDL, and the branching ideogram versions of docu- 
mentation were the most effective for answering the tracing 
questions. 

For the input/output questions, no significant 
differences were found between the forms of documentation. 
The most preferred combinations of documentation formats 
were the PDL symbology and the branching spatial arrange- 
ments [Ref. 11 ]. 
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In another experiment programmers ware asked zo 
complete the coding of portions of programs referencing only 
the documentation under test. In this experiment tha 

English narrative format took significantly longer to 

produce code than did the PDL format. The English version 
also produced tha largest number of errors, while the PDL 
produced the smallest. 

The spatial arrangement effects were not signifi- 
cant, tut the formats of the sequential PDL and the 
branching PDL arrangements produced the best experimental 
results. The sequential English version produced the 
poorest performance. 

The programmers also chose the PDL branching 
arrangements as the preferred format combination. 

In yet another experiment the programmers had to 
correct error-seeded programs, again utilizing only the 
documentation under test as a source of program information. 

.The bast results in performance occurred with the 
PDL and ideogram symbologies for this experiment. The 
spatial effects were again not significant. The sequential 
and branching PDL formats proved to be high performers, as 
did the branching and hierarchical ideograms. 

The programmers had no preference for the type of 
symbology in this experiment, but they did prefer the 

branching spatial arrangement [Ref. 13]. 

Though slightly different results were produced in 
this experiment depending on the maintenance task, overall 
the indication is that performance is improved when the 
symbology is of a succinct nature, such as in the PDL 

format. The English narrative proved to be too wordy and 
awkward to provide efficiency when attempting software 
maintenance. 

As for the spatial arrangement issue, the best 
overall performance resulted from the use of a branching 
arrangement in providing the clearest display of control 



52 



flow. The PDL branching format, then, seemed no promote 
understandabilit y for the maintainer, and the PDL branching 
format was selected by the programmers as the easiest 
overall format to use. 

2. Doc ume n tat ion for Concurrent Processing 

Since much of today’s program processing is concur- 
rent, it is wise to investigate documentation effectiveness 
for the concurrent realm of processing. Concurrent 

processing of programs entails two or more portions of the 
program executing simultaneously. Because of the complexity 
involved with concurrent processes, programs that contain 
concurrent processing must be carefully documented. It is 
important to convey information about the control flow of 
the program and the sharing of resources. 

The formats of documentation used for the General 
Electric studies of concurrent processing documentation 
[Ref. 14] consist of three types: PDL; resource diagrams; 

and Petri nets. The first form of documentation is the same 
PDL as used in the sequential processing tests. The PDL 
emphasizes the control-flow characteristics of the program. 

The second form of documentation, the resource 
diagram, places emphasis on the concept of providing 

resource sharing information to the programmer. The 
resource diagram uses communication circles containing 
abbreviated English statements to convey information about 
the relationships between processes. Natural English state- 
ments provide narrative information contained in process 
boxes to describe the process itself. Resource diagrams are 
arranged spatially in a branching format similar to the 
branching organization used in the sequential experiments. 

The third form of documentation is that of a Petri 
net. Petri nets have nodes that contain information that 
indicates resource usage for required tasks, while 
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con*rol-flow information is convsyed with a constrainsS 
language description. The Petri net format of documenraticn 
places equal emphasis on control-flow and resource sharing 
information. The spatial arrangement of the Petri net is 
also similar to that of a branching organization. 

In the concurrent processing experiment programmers 
were asked to make either data-struct ur e or control-flow 
modifications to each of three programs. For both types of 
modifications, the resource diagrams proved to be the besn 
performers. The Petri net gave the poorest performance. 

Since the resource diagrams emphasize information 
about the resource-sharing aspect of rhe processing of the 
program, it is interesting to none rhat the control-flow 
information that was so important for the sequential 
processing of a program is not as vital for the maintenance 
of concurrent processes. 

When asked to select the documentation format that 
was easiest to use, the PDL format was selected. It turned 
out, however, that the most efficient form of documentation 
for the concurrent processing was the resource diagram. 

B. DISCOSSION 

The results of the experiments yield some ideas that can 
be- incorporated into explicit documentation types for 
program documentation. With proper incorporation of the 
ideas, understandabilit y can be enhanced for maintainers 
resulting in a .positive influence on maintenance 
efficiency. 

When determining the type of documentation to be 
accessed in the documentation hierarchy of Figure 4.1 in 
Chapter III, it is important to realize that there is not 
one “best" form of documentation for all maintenance tasks. 
The type of processing (sequential or concurrent) must be 
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taken into account when identifying the bes- do cumenta-^ ion 
format tc include in the hierarchy. This processing infor- 
mation is provided in a narrative sense in level 3. Level U 
will provide the actual flew information, be it resource- 
flow or control- flow information. 

The General Electric studies show support for the 
concept of minimal documentation introduced in chapter II. 
The English narratives were found to be too long and awkward 
for the best performance of maintenance. When the method of 
transferring information took on the more abbreviated form 
of the PDL, maintainers showed a preference for this format 
of symbology presentation. This preference held true for 
both the sequential and the concurrent programming techni- 
ques. The implication is that, even though the ideas 
conveyed in both the formal English narrarive and the PDL 
were the same, the programmers chose the succinct method of 
symbology as being easier to glean the necessary informa- 
tion for the maintenance task. k significant point is that 
the programmers chose not tc wade through all the super- 
fluous language provided by the English narrative, thus 
indicating a preference for minimal documentation. As far 
as sequential processing is concerned, the PDL proved to 
be not only the programmer's choice for symbology represen- 
tation, it also proved to be the most efficient. In the 
case of the concurrent processing, the PDL was the preferred 
method of symbology representation, but the resource diagram 
proved to be more efficient. 

The concept of minimal documentation is not contradicted 
by the fact that the PDL form of symbology was preferred by 
programmers, but resource diagrams proved to be the mosc 
efficient for maintenance purposes in concurrent program- 
ming. The fact is that the information required for concur- 
rent processing maintenance is simply different than the 
information that is provided by the PDL. Concurrent 



55 



processing requires information with emphasis on the 
resource-sharing aspect of the program, while the ?DL 
provides information primarily concerning the aspect of 
control-flow (which is of primary concern in the sequential 
processing program) . In this experiment it turned out that 
the actual minimal documentation was the resource diagram, 
and not the PDL the maintainers preferred. 

When determining which format of documentation to access 
for the performance of maintenance, the format which best 
suits the task at hand should be considered in the selection 
process with emphasis on maintenance efficiency. When the 
proper level (or levels) of documentation are selected from 
the documentation hierarchy, along with the best physical 
representation of the documentation, then minimal documenta- 
tion is accessed and effective underst andability is 
achieved. The end result is an affective and efficient 
performance of the maintenance task. 
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VI. CONC LOGONS AND a 2C3 a ilBN D&TIONS 



Since maintenance costs make up the largest part of most 
software projects, it is vital zo find effective ways to 
reduce or make more efficienr the software maintenance 
effort. When good documentation techniques are incorporated 
into the project evolution, then development ideas and other 
relevant information about the system can be successfully 
recorded and transferred to other individuals. 

Since it is critical that good documentation techniques 
be emphasized, accurately determining the precise type and 
amount of documentation for software maintenance is vital. 
Minimal documentation is the result of that determination 
and should, therefore, be incorporated into software 
projects where appropriate. (Some programs are simply not 
maintained and therefore do not need maintenance oriented 
documentation. ) 

Managers of the maintenance team often have misconcep- 
tions about how the time spent on software maintenance 
should be allocated. Because of these misconceptions, a 
closer look at how maintenance time is spent is in order. 
Perhaps an analysis of the maintenance effort on each 
project should be conducted so as to determine how the main- 
tenance time is actually spent. The manager can then have 
an effective tool with which to schedule the maintenance 
effort without having to resort exclusively to the use of 
intuition. 

Programmers should be trained not only to document the 
system as it develops, but to do so keeping the maintenance 
aspect in mind. Maintenance enhancing documentation should 
be developed simultaneously with the project as an integral 
part cf the system. 
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Programmers must become aware of the fact that there is 
not one ’’best" format of documentation for all rypes of 
maintenance. More research like the General Electric 
studies should be conducted in order to determine the best 
documentation format for the particular maintenance task 
being performed. A particular format, then, should not be 
taught as the only proper way to document a program. 

Well trained programmers will also raise the skill level 
of the maintenance team, and as skill level increases, the 
need for detailed explicit documentation decreases. The 
skilled programmer can then accepc larger conceptual ideas 
about the program, thus avoiding the need to search through 
a large volume of information in order to perform the tasx 
at hand. Maintenance and cost efficiencies are therefore 
enhanced. 

Since programmers have mors confidence in internal docu- 
mentation, it is recommended that, to the extent feasible, 
information be carried internally along with the source 
code. As "hard” copies are needed, they could simply be 
printed cut for a specific use. Perhaps a physical copy of 
the documentation should be filed for back up purposes, but 
the amount of external copies should be kept to a minimum in 
order to avoid the reluctance to keep the hard copies 
updated. In all cases, however, all forms of documentation 

should be updated as modifications to -he software are made 
in order to ensure that the documentation is an accurate 
reflection of the project. 

In support of achieving minimal documentation, the 
internally stored documentation should be organized in the 
format of a documentation hierarchy. Thera should be one 
hierarchy structure that will contain all types of explicit 
documentation, and each physical format will be classified 
and filed according to the level of detail contained in the 
document. This "level of detail” type of categorization will 
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necessarily 


cause the 


documentation to become 


a 


p a r*t 


of 


either the 


system or th 


e program documentation. 








Users, 


managers. 


and maintainers should 


be 


able 


to 


access the 


appropriate 


piece of documentation 


based on 


the 



amount of detail needed for the particular task at hand. 
The system should be set up in such a way that each level is 
easily accessed, and a method of moving up or down the hier- 
archical organization should be made available. 

It is recommended that further research be conducted 
into the implementation of the hierarchical scheme in a menu 
driven window format that can display the indicated piece of 
documentation on a display screen for perusal. A pointer 
device can point to a place on the menu to request a partic- 
ular level in the hierarchy. The capability to transcend to 
different levels will be built into the menu operation of 
the windows. This documentation hierarchy implementation 
will provide a powerful documentation tool that promotes the 
minimal documentation concept, and should result in an effi- 
cient maintenance effort. 
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